home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 38 / Amiga Format CD38 (1999-03-15)(Future Publishing)(GB)(Track 1 of 3)[!][issue 1999-04].iso / -in_the_mag- / reader_requests / dice_v3.15 / doc / dcc.doc < prev    next >
Text File  |  1999-01-26  |  33KB  |  843 lines
  1.  
  2. dcc/dcc                                 dcc/dcc
  3.  
  4.                 DCC.DOC
  5.  
  6.                   Matthew Dillon
  7.                   891 Regal Rd.
  8.                   Berkeley, Ca. 94708
  9.                   USA
  10.  
  11.                   dillon@overload.Berkeley.CA.US        --or--
  12.                   uunet.uu.net!overload!dillon
  13.  
  14.                   BIX: mdillon
  15.  
  16.     DCC <options and files>
  17.  
  18.     NOTE:   new this version, use of single precision IEEE libraries for
  19.     floating point.   Please read the note under the option '-ffp' for
  20.     more information.
  21.  
  22.     DCC is similar to the UNIX 'cc' command and is the frontend for the
  23.     DICE compiler.  For best performance I strongly suggest that you make
  24.     DCC, DC1, DCPP, DAS, and DLINK resident.  If you do not have enough
  25.     memory to do so you at least want to leave the largest programs, DC1
  26.     and DAS resident.    It is suggested that your machine have at least 1MB
  27.     of memory.    A compile or link can take as much as 400K of run-time
  28.     memory.
  29.  
  30.     Options may occur anywhere on the command line but MUST occur singly.
  31.     That is, -c -a instead of -ca.  file arguments to options may occur
  32.     with or without an intervening space.  -oFILE and -o FILE are both legal.
  33.  
  34.     Files ending in .a[sm] are assumed to be assembly files.  Files ending
  35.     in .l[ib] are assumed to be library files.    Files ending in .o[bj] are
  36.     assumed to be object files.  All other files are assumed to be C source
  37.     files.
  38.  
  39.     Normally DCC compiles all C source files, assembles all .a[sm] files,
  40.     and links the resulting object files with any specified .o files
  41.     together to produce an executable.    The output file may optionally be
  42.     specified with the -o option.  If not specified, a default output
  43.     filename based on the name of the input file is generated.    This
  44.     general action is modified by two options:
  45.  
  46.     -c    DCC does NOT link, -o specifies the output object file
  47.  
  48.     -a    DCC does NOT assemble (i.e. leaves the .a file resulting from
  49.         a compile).  -o specifies the output assembly file
  50.  
  51.     If neither option is given -o specifies the name of the resulting
  52.     executable.
  53.  
  54.     The default object directory is T: and may be changed with the -O option.
  55.     The default temporary directory is also T: and may be changed with the -T
  56.     option.  IF YOU HAVE LIMITED MEMORY you may have to specify that
  57.     temporary files not be placed in T: either by re-assigning T: or using
  58.     the -T option.  DICE goes much slower if temporary files must be written
  59.     to a floppy or even a hard disk.
  60.  
  61.     WARNING: .a[sm] files are assembled with DAS, read DAS.DOC if you
  62.     intend to assemble non-DC1 generated assembly.
  63.  
  64.         ------------------- OPTIONS ------------------
  65.  
  66.     file    File to compile, assemble (.a), and/or link (.o, .lib)
  67.  
  68.     @file    File containing further list of files, one per line.
  69.         (blank lines and lines beginning with ';' or '#' are
  70.         ignored.  File may NOT contain further options).
  71.  
  72.     -E file    specify stderr file, any errors are appended to the file
  73.         instead of to stdout.  Useful for batch compiles
  74.  
  75.     -c        Compile C source files and assemble into OBJECT files
  76.         only (do not link).
  77.  
  78.     -a        Compile C source files into ASSEMBLY files (do not assemble
  79.         or link).
  80.  
  81.         Keep in mind the DAS will do further optimizations on the
  82.         assembly file that you see.
  83.  
  84.     -l0     Do not link default libraries (dlib:c.lib dlib:amigas.lib
  85.         dlib:auto.lib), or standard startup (dlib:c.o and
  86.         dlib:x.o).
  87.  
  88.         BEGINNER'S NOTE:    Do not use this option
  89.  
  90.         This option is used in special circumstances, such as when
  91.         generating .libraries or .devices.
  92.  
  93.         WARNING: DICE is much more dependant on its startup code
  94.         (c.o and x.o) than other compilers, do not link without
  95.         the startup unless you know what you are doing.
  96.  
  97.     -l lib    When linking include this library. (space is optional)
  98.  
  99.         Generally -l is used to include the math library (-lm)
  100.         when formatted floating point *printf()s are required.
  101.  
  102.         Refer to the section 'MODELS AND LIBRARIES' and 'CREATING
  103.         YOUR OWN LIBRARIES' below for more information on linking
  104.         in custom libraries.
  105.  
  106.     -2.0    Default amiga.lib is    dlib:amigas20.lib
  107.         Default amiga include path is dinclude:amiga20/
  108.  
  109.         -2.x where 'x' is the second digit replacing the '0' in the
  110.         above example.    This option is useful when compiling for
  111.         different versions of the operating system.
  112.  
  113.     -1.3    Like -2.0, but using dlib:amigas13.lib and dinclude:amiga13/
  114.  
  115.         Again, -1.x may be specified.
  116.  
  117.     -L0     remove default library search path, including all explicitly
  118.         specified (-L dir) directories up to this point.
  119.  
  120.     -L dir    add the specified directory to the library search path.  If
  121.         the object module or library can not be found in the
  122.         current directory, directories specified with -L are
  123.         searched.  -L directories are searched before the default
  124.         library directory (DLIB:), assuming it was not removed
  125.         with -L0 .
  126.  
  127.         Note that the directory path specified by -L is used to
  128.         search for libraries AND object modules.
  129.  
  130.         A trailing '/' is optional
  131.  
  132.     -I0     remove default include path from search list.  The default
  133.         include path is dinclude: and dinclude:amiga/ (unless
  134.         modified by -1.x and -2.x options)
  135.  
  136.     -I dir    When compiling scan this include directory (space is
  137.         optional) The specified path takes precedence over defaults
  138.         but defaults are NOT removed.
  139.  
  140.     -D define[=value]
  141.         Pre-define a symbol
  142.  
  143.     -U        undefine __STDC__, mc68000, _DCC, and AMIGA.
  144.  
  145.     BEGINNER'S NOTE:    Do not use any of these options
  146.  
  147.     -H<outfile>=<hdrfile>
  148.  
  149.     This option enables precompiled header file generation and
  150.     operation. You may specify any number of -H options.  Example
  151.     usage:
  152.  
  153.     -Ht:defs.m=defs.h
  154.  
  155.     When DICE encounters an #include <defs.h> this will cause it to
  156.     first check for the existance of T:DEFS.M ... if T:DEFS.M does
  157.     not exist DICE will generate it from <defs.h>.    if T:DEFS.M
  158.     does exist then DICE will use it directly and ignore <defs.h>
  159.  
  160.     You must specify the -H option both to have DICE create the
  161.     precompiled header file and to have DICE use the precompiled
  162.     header file.  Normally one makes operation as transparent as
  163.     possible so as not depend on the option existing when porting
  164.     to other enviroments.
  165.  
  166.     WARNING WARNING WILL ROBINSON!    A precompiled header file contains
  167.     the preprocessed header and preprocessor macros.  These are set in
  168.     stone!    If you modify a #define that would normally effect
  169.     preprocessing of a header file which is precompiled THE EFFECT WILL
  170.     NOT OCCUR.  It is strongly suggested you use precompiled headers
  171.     ONLY with includes that are pretty much unchanging.  For example,
  172.     the commodore includes or otherwise have an appropriate dependancy
  173.     in your DMakefile or make script to delete the precompiled header
  174.     file whenever any of your headers are modified.
  175.  
  176.     Normally one has a single -H option that enables precompiling of a
  177.     local header file, say DEFS.H, which contains #include's of all
  178.     other header files.  Source modules would then #include <defs.h>
  179.  
  180.     BEGINNERS'S NOTE:   Do not use this option
  181.  
  182.     -o file    Specify output executable, object, or assembly file name
  183.         depending on what you are producing.  The space is optional
  184.  
  185.     -020    generate code for the 68020 and later microprocessors
  186.     -030    generate code for the 68030 and later microprocessors
  187.     -881    generate inline FFP code for the 68881
  188.     -882    generate inline FFP code for the 68882
  189.  
  190.     BEGINNER'S NOTE:    Do not use any of these options
  191.  
  192.     These options exist to produce 020 and 030 opcodes, and 881/882
  193.     inline assembly for floating point operations.    They are not
  194.     necessarily implemented yet.  The intent is to implement them
  195.     by V2.06 .
  196.  
  197.     -md     small data model (default)      uses A4-relative
  198.     -mD     large data model        uses absolute-long
  199.     -mc     small code model (default)      uses PC-relative
  200.     -mC     large code model        uses absolute-long
  201.  
  202.     BEGINNER'S NOTE:    Use only -mD if you declare more than
  203.     64KBytes of data.
  204.  
  205.     These options specify the default data and code model to use.
  206.     The model may be overriden by use of the __near and __far
  207.     type qualifiers (see EXTENSIONS.DOC) on a variable by variable
  208.     basis.
  209.  
  210.     DICE defaults to the small data and small code model, and is able
  211.     to generate >32KBytes of code using the small code model so you
  212.     should never have to use -mC.  Note that the DICE libraries have
  213.     all been compiled with the small-data model, and certain
  214.     applications may disrupt the base register, A4... in this case
  215.     use of the __geta4 type qualifier should be of use.  If worse
  216.     comes to worse you can recompile a large-data model C.LIB, but
  217.     I suggest you try other solutions first.
  218.  
  219.     -ms0    (default), only const objects are put into a CODE hunk
  220.     -ms1/-ms    string constants are put into the read-only code hunk
  221.     -ms2    string constants are put into the read-only code hunk AND
  222.         all external const references use NEAR addressing
  223.  
  224.     BEGINNER'S NOTE:    Use only -ms
  225.  
  226.     -ms0 turns off -ms1/-ms2 in case you have it in your DCCOPTS
  227.     enviroment variable and want to turn it off.
  228.  
  229.     Default operation (no -ms1/-ms2) puts 'const' items into a
  230.     read-only CODE hunk.  Locally declared objects are referenced using
  231.     PC-REL while external objects (declared in some other module) are
  232.     referenced using 32-BIT ABSOLUTE addressing.
  233.  
  234.     -ms will additionally make all string constants, such as "fubar",
  235.     const and referenced via PC-REL.  -ms is an extremely useful option
  236.     when you will never modify any of your string constants because the
  237.     strings are not copied for multiple running instances of the
  238.     program (if resident).
  239.  
  240.     -ms2 works like -ms1, but in addition forces all external const
  241.     references to use PC-REL addressing INSTEAD of 32-bit absolute
  242.     addressing.  THIS IS A VERY DANGEROUS OPTION, DO NOT USE UNLESS THE
  243.     FINAL CODE SIZE IS LESS THAN 32 KBytes.
  244.  
  245.     Using -ms along with -r can result in huge savings of memory due to
  246.     the string constants being moved out of the data segment (which
  247.     must be duplicated for each running instance of the program).
  248.  
  249.     WARNING WARNING.  In all cases if you declare an object as 'const'
  250.     it must be extern'd as 'const' in other modules or incorrect code
  251.     will be generated.  This is true whether you use -ms/S or not.
  252.  
  253.     -mr     registered arguments, light
  254.     -mR     registered arguments, medium
  255.     -mRR    registered arguments, strict
  256.  
  257.     BEGINNERS NOTE:     either do not use these options or use only -mr
  258.     BEGINNERS NOTE:     see REGARGS.DOC
  259.  
  260.     These options control the automatic registerization of procedure
  261.     arguments.  Only those prototyped procedures declaring 4 or fewer
  262.     arguments will be registered.  Values are passed in D0/D1/A0/A1
  263.     according to the type of variable and availabilty of registers/
  264.  
  265.     -mr This option is obsolete
  266.  
  267.     -mR generates only a single, registered entry point
  268.  
  269.     -mRR is similar to -mR but extends registerization to indirect
  270.         function calls (that are fully prototyped).  This is the
  271.         most dangerous option.
  272.  
  273.     Note that -mr and -mR assign the normal, nonregistered entry point
  274.     of a function to any indirect function pointers whether they are
  275.     fully prototyped or not (e.g. void (*func)() or void (*func)(int) )
  276.  
  277.     -mRR assigns either the registered or normal entry point to
  278.     function pointers depending on whether they are prototyped or not
  279.     (and any calls made through these function pointers will use the
  280.     registered args method).
  281.  
  282.     WARNING:    -mR CANNOT BE USED IF YOU MAKE C.LIB CALLS THAT TAKE
  283.     CALL-BACK FUNCTIONS AS ARGUMENTS.  -mr and -mRR *CAN* be used,
  284.     however with -mRR you must be careful to supply the registered
  285.     entry point.
  286.  
  287.     WARNING:    AMIGA.LIB ROUTINES THAT TAKE CALL-BACK FUNCTIONS AS
  288.     ARGUMENTS MUST BE GIVEN NON-REGISTERED ENTRY POINTS.  Thus if
  289.     you use -mRR you *must* qualify the procedure or function pointer
  290.     type specification with __stkargs to entire it has a normal
  291.     entry point.
  292.  
  293.     -mi     Inline library calls
  294.  
  295.     Causes DICE to utilize inline library calls instead of library
  296.     tags.  DCC will pass -D__DICE_INLINE to the preprocessor which
  297.     causes inline stuff in <clib/*_protos.h> to be brought in.
  298.     Your programs must #include appropriate prototype headers
  299.     such as:
  300.  
  301.     #include <clib/exec_protos.h>
  302.  
  303.     These are Commodore standard prototype files which DICE postpends
  304.     with appropriate inline specifications when the -mi option is
  305.     used.  If the -mi option is not used the prototype files will
  306.     still work as expected but no inline calls will be made.
  307.  
  308.     -mw <addr>    USED FOR MAKING ROMABLE EXECUTABLES, DO NOT USE TO CREATE
  309.         AMIGA EXECUTABLES
  310.  
  311.     BEGINNER'S NOTE:    Do not use this option
  312.  
  313.     This option is another data model, called the ABSOLUTE-WORD data
  314.     model.    Source files compiled with this option generate
  315.     absolute-word data references to access data objects instead of
  316.     A4-relative or absolute-long.  The base of the data segment must be
  317.     specified as decimal, 0octal, or 0xHEX.
  318.  
  319.     Since absolute-word is used exclusive of A4-relative, the compiler
  320.     will now use A4 for register variables.  You may NOT mix -mw
  321.     modules with small-data models (do NOT use C.LIB, see ROMABLE.DOC)
  322.  
  323.     The ROMABLE program is usually run on the executable generated by
  324.     DLink to generate a ROM.
  325.  
  326.     -ma <addr>    USED FOR MAKING ROMABLE EXECUTABLES, DO NOT USE TO CREATE
  327.         AMIGA EXECUTABLES
  328.  
  329.     BEGINNER'S NOTE:    Do not use this option
  330.  
  331.     This option specifies to the compiler and linker that the resulting
  332.     code is intended to be relocated to a permanent data address, that
  333.     specified by <addr> in decimal, 0octal, of 0xHEX.
  334.  
  335.     Unlike -mw, -ma assumes that the data segment can be placed
  336.     anywhere.  The ROMABLE program is usually run on the executable
  337.     generated by DLink to generate a ROM.
  338.  
  339.     You may still specify a data model, -md or -mD, to use with this
  340.     option.  Unlike -mw, -ma does NOT touch the A4 register and thus
  341.     may be mixed with the small-data model.  Again, see ROMABLE.DOC
  342.  
  343.     -rom    SET UP OPTIONS FOR GENERATING ROMABLE CODE
  344.  
  345.     BEGINNER'S NOTE:    Do not use this option
  346.  
  347.     Like -l0, -rom disables automatic inclusion of a startup file (you
  348.     must specify your own) and libraries.  However, x.o is still
  349.     included to sink any autoinit code.  Your startup code must handle
  350.     the appropriate model and call autoinit code before calling your
  351.     program main
  352.  
  353.     This option is used to support ROMed firmware, i.e. non-amiga
  354.     executables.  You should never link with C.LIB.  Instead, a new
  355.     library, ROM.LIB, is available.
  356.  
  357.     ROM.LIB contains no static or global references and thus works
  358.     with any data model, and only completely self-contained routines
  359.     are included.  The only data ROM.LIB uses is stack-based.  All
  360.     ROM.LIB routines are completely reentrant, including
  361.     [v]sprintf() !
  362.  
  363.     -proto    PROTOTYPE CHECKING AND OPTIMIZATIONS
  364.  
  365.     When this option is used, an ERROR message will be generated for
  366.     any call that is not prototyped.  This option is useful to ensure
  367.     that you have properly prototyped routines (when you use
  368.     prototypes), especially when floats and doubles are passed and
  369.     indirect function pointers are used (they must be prototyped as
  370.     well!).
  371.  
  372.     IN THE FUTURE THIS WILL ENABLE STACK-ARGUMENT OPTIMIZATION.
  373.     Currently, chars and shorts are extended to long's when pushed onto
  374.     the stack for a subroutine call.  In the future if the -proto
  375.     option is used these objects will be pushed as shorts and not
  376.     extended.
  377.  
  378.     -prof    enable profiling for source modules
  379.     -prof1    same as -prof
  380.     -prof2    enable profiling for source modules and c*p.lib
  381.     -prof3    enable profiling for source mods, c*p.lib, and amiga*p.lib
  382.  
  383.     Enable profiling.  You may compile some or all your source modules
  384.     with profiling enabled.  Any -prof* option will enable profiling
  385.     for compiled source modules.  -prof2 will cause DCC to link
  386.     with a profiled c*p.lib while -prof3 will cause DCC to link
  387.     with a profiled c*p.lib AND amiga*p.lib (the ultimate).
  388.  
  389.     To profile c*.lib and/or amiga*.lib functions the equivalent
  390.     c*p.lib and amiga*p.lib must exist.  These libraries are most
  391.     likely lharc'd in DCC2:dlib/ or DCC3:dlib/ but if not, registered
  392.     users may create any link library from the library source.
  393.  
  394.     -r        Make executable residentable with separate CODE & DATA hunks
  395.     -pr     Make executable residentable w/ no relocation hunks
  396.     -pi     Make executable NON-residentable w/ no relocation hunks
  397.  
  398.     BEGINNER'S NOTE:    Just use -r to get residentable executables and
  399.     do not worry about these other options.
  400.  
  401.     -pr/-pi generate 'position independant' code also useful for ROMed
  402.     applications.  NOTE that -pi and -pr force const items to be
  403.     referenced pc-relative as well, causing -ms and -mS to do the same
  404.     thing (when combined with -pr/-pi)
  405.  
  406.     CODE SIZE IS LIMITED TO 32KBYTES WHEN YOU USE -pr OR -pi
  407.  
  408.     Refer to the section below called 'RESIDENTABILITY' for a
  409.     discussion of these options
  410.  
  411.     NOTE ROPT1:    You may not make data references within const
  412.     declared objects when using the -r/-pr options.  This is because
  413.     the CODE hunk is shared between running instances of the program
  414.     and these address references would be different between the
  415.     instances.
  416.  
  417.     However, if you are using the -ms option, string constants will
  418.     be in the code section and thus no problem.
  419.  
  420.     -O outdir    Specify directory that is to contain output executable,
  421.         object, or assembly files (used when specifying multiple
  422.         source files)
  423.  
  424.     -O is useful to tell the compiler where to put the objects
  425.     when you use dcc to compile and link a whole bunch of files
  426.     at once.  In this case, the -o option can still be used to
  427.     specify where to put the final executable.
  428.  
  429.     NOTE:    The -O name is used as a prefix so if you are
  430.     specifying a directory be sure it has a ':' or '/' on
  431.     the end.
  432.  
  433.     -T tmpdir    Specify the temporary directory used to hold preprocessed
  434.         source files and temporary assembly files... files that
  435.         will be deleted after use.
  436.  
  437.     NOTE:    The -T name is used as a prefix so if you are
  438.     specifying a directory be sure it has a ':' or '/' on
  439.     the end.
  440.  
  441.     The default is T: .. this option is useful in low-memory situations
  442.     where you may decide to put intermediate files elsewhere.  Putting
  443.     intermediate files on your HD or floppy slows down compilation by
  444.     an order of magnitude, but if you are running on a system with
  445.     little memory you may not have a choice.
  446.  
  447.     -s        Include symbolic debugging information in the executable.
  448.         (dlink opion)
  449.  
  450.     This option includes the symbol table in the resulting executable
  451.     and is passed to dlink.  When using DOBJ to disassemble an
  452.     executable, DOBJ will use the symbol table to generate a more
  453.     symbolic dump.
  454.  
  455.     -S        ALTERNATE SECTION NAMING OP FOR LIBRARIES
  456.  
  457.     When making libraries: uses alternate section naming conventions so
  458.     that all initialized data in the module will be placed before any
  459.     initialized data in non -S modules (i.e. normal linked object
  460.     files).  Any library BSS will be placed before non-library BSS.
  461.     Thus, the final ordering in the final executable will be:
  462.  
  463.         [LIBDATA] [PROGRAMDATA] [LIBBSS] [PROGRAMBSS]
  464.  
  465.     Thus, if your program contains >64K Bytes of BSS you can still
  466.     link with a library that tries to reference its own BSS using
  467.     the small-data model.  If your library declares only initialized
  468.     data (i.e. int x = 0; ), then you can link with the library even
  469.     if your program declares >64KBytes of *initialized* data !
  470.  
  471.     -v        Display commands as DCC executes them.
  472.  
  473.     -new    Checks timestamps for source/destination and only
  474.         compiles/assembles if object is outdated or does not
  475.         exist.    Used to make DCC a standalone make.
  476.  
  477.     -f        FAST / ^C HANDLING FOR 1.3
  478.  
  479.         This option is used for 1.3 only.  You MUST be using the
  480.         commodore shell (NewShell) and if you make programs
  481.         resident you MUST use the commodore C:Resident command.
  482.  
  483.         This option will probably not work if you use WShell or
  484.         ARPShell under 1.3.  This option allows DICE to take
  485.         short cuts to run sub-programs and allows ^C to be
  486.         propogated to said programs.  This option is useful
  487.         to set permanently in your DCCOPTS ENV: variable if
  488.         you run under 1.3
  489.  
  490.         DICE under 2.0 has no such problems and will run sub
  491.         programs optimally, including propogation of ^C.
  492.  
  493.     -frag    FRAGment (linker option).
  494.  
  495.     Tell linker not to combine all code hunks together or combine all
  496.     data hunks together. Cannot be used if the -r or -mw options are
  497.     used. Generally only useful if the large-data model is used.  Not
  498.     entirely supported yet.
  499.  
  500.     -ffp    Set fp library for floats
  501.     BEGINNER'S NOTE:    When using single precision floating point
  502.     this option, use of the original ffp libraries, will make the
  503.     program portable across all amigas.  Otherwise only amigas that
  504.     have the commodore MathIeeeSing*.library libraries will be
  505.     able to run the program.
  506.  
  507.     If not specified, 'mathieeesingtrans.library' and
  508.     'mathieeesingbas.library' are used.  These are new 2.0 libraries
  509.     that may not exist on all machines yet.
  510.  
  511.     If specified, 'mathtrans.library' is used .. motorola's FFP float
  512.     library.
  513.  
  514.     NOTE:  IF -ffp is used, be warned that conversion from floats to
  515.     doubles and back again is not entirely reliable.
  516.  
  517.     -d#     Set debugging level (# = a number), used for compiler
  518.         diagnostics only.
  519.  
  520.     -d<opts>    Specify any combination of debugging options.  These options
  521.         may be combined in one -d option.
  522.  
  523.         Currently no options are defined.
  524.  
  525.     -gs     Generate Dynamic Stack Code.  This generates code on every
  526.         subroutine call to check available stack.  If available
  527.         stack falls below 2K a new stack frame is allocated which
  528.         will be deallocated when the subroutine returns.
  529.  
  530.         If the allocation fails, stack_abort() is called.  If this
  531.         routine is not defined by you, the library stack_abort()
  532.         will call abort().  REFER TO DOC/EXTENSIONS.DOC FOR
  533.         MORE INFO.cd src
  534.  
  535.  
  536.         This option is extremely useful when compiling UNIX code
  537.         that expects infinite stack.
  538.  
  539.     -chip    CHIP force (linker option).
  540.  
  541.     Tell linker to force all hunks into CHIP memory.  You should
  542.     generally not use this option.    Instead, use the __chip
  543.     keyword (see EXTENSIONS.DOC) for those specific data items
  544.     that need to be in CHIP memory.
  545.  
  546.     NOTE:    CHIP data items are accessed using the large-data
  547.     model, thus you cannot create residentable executables that
  548.     contain __chip declarations UNLESS THEY ARE ALSO 'const'
  549.     objects -- read-only.
  550.  
  551.     -unix
  552.  
  553.     Causes DICE to use DLIB:uc*.lib instead of DLIB:c*.lib    ... the
  554.     uc*.lib is exactly the same as the normal c*.lib except that all
  555.     filenames are assumed to be UNIX names .. that is, a beginning
  556.     slash is converted to ':' (root of the current volume), "./" is
  557.     ignored, and "../" is converted to "/" for all file accesses.
  558.  
  559.     This makes porting and usage of UNIX programs easier.
  560.  
  561.     -aztec    The front end attempts to run Aztec executables
  562.     -lattice    The front end attempts to run Lattice executables
  563.     -sas    same as -lattice
  564.  
  565.     These options allow one to write a single DMakefile able to handle
  566.     compilation under any compiler, assuming the source is compilable
  567.     under any compiler.
  568.  
  569.     These are very limited options and may not work across new
  570.     versions of Aztec or Sas/C
  571.  
  572.     -//
  573.     This option enables C++ style // comments.  This form of commenting
  574.     begins with a // causing it and the remainder of the line to be
  575.     considered a comment.
  576.  
  577.     -no-env
  578.     This option disables DCCOPTS.  DCC will not process options in
  579.     the DCCOPTS enviroment variable.
  580.  
  581.  
  582.     The ENV:DCCOPTS enviroment variable may contain additional options.
  583.  
  584.     ENV: must exist for DCC to run, even if you do not have a DCCOPTS
  585.     enviroment variable.  If you do not use ENV: then assign it to RAM:
  586.  
  587.  
  588.     Example #1.  Compile hello.c to executable.  The objects will be
  589.         left in T:
  590.  
  591.     1> dcc hello.c -o ram:hello
  592.     1> ram:hello
  593.  
  594.     Example #2.  Compile hello.c to executable and put the object file
  595.         in X:
  596.  
  597.     1> dcc hello.c -o ram:hello -TX:
  598.  
  599.     Example #3.  Compile hello.c into object into RAM: then link with symbols
  600.  
  601.     1> dcc -c hello.c -o ram:hello.o
  602.     1> dcc ram:hello.o -o ram:hello -s
  603.  
  604.     Example #4.  Compile foo.c and link with an already compiled object file
  605.          gar.o to produce an executable.  foo.o is placed in
  606.          T:
  607.  
  608.     1> dcc foo.c gar.o -o ram:foogar
  609.  
  610.                   PREPROCESSOR
  611.  
  612.     Predefined Symbols:
  613.  
  614.     __LINE__        current line number (integer constant)
  615.     __DATE__        current date (string)
  616.     __TIME__        current time (string)
  617.     __FILE__        current file (string)
  618.  
  619.     __BASE_FILE__        base source file (string), allows specification
  620.                 of the actual name of the source file from
  621.                 within an include file.
  622.  
  623.                 (-U undefines the below symbols)
  624.     __STDC__
  625.     mc68000
  626.     _DCC
  627.     AMIGA
  628.     _FFP_FLOAT        set if single prec. floats are in FFP format
  629.     _SP_FLOAT        set if single prec. floats are in IEEE-SING format
  630.                 (default)
  631.  
  632.     NOTE:  There are no limits to symbol and macro lengths.
  633.  
  634.                    MODELS AND LIBRARIES
  635.  
  636.     DICE supports various memory models and this is closely coupled with
  637.     the link libraries it picks.  There are two major memory models that
  638.     effect the link library selection:
  639.  
  640.     -mRR        registerized procedure calls
  641.     -md/-mD     small data / large data
  642.     -prof1        profiled user code
  643.     -prof2        profiled c.lib
  644.     -prof3        profiled c.lib and amiga.lib
  645.  
  646.    Library naming convention works as follows:
  647.  
  648.     <libraryname>[srpl].lib
  649.  
  650.     l - large data model    \ one of these two will always be specified
  651.     s - small data model    /
  652.     r - registered arguments, else stack arguments
  653.     p - profiled link library, else not profiled
  654.  
  655.     Keeping that in mind, these are the libraries that come with the
  656.     registered version of DICE:
  657.  
  658.     cs.lib        small data
  659.     csr.lib     small data + registered args
  660.     csp.lib     small data + profiled
  661.     csrp.lib    small data + registered args + profiled
  662.  
  663.     ms.lib        small data
  664.     msr.lib     small data + registered args
  665.     msp.lib     small data + profiled
  666.     msrp.lib    small data + registered args + profiled
  667.  
  668.     amigal13.lib    large data amiga.lib for 1.3 (commodore 1.3 amiga.lib)
  669.     amigas13.lib    small data amiga.lib for 1.3
  670.     amigasp13.lib    small data profiled amiga.lib for 1.3
  671.  
  672.     amigal20.lib    large data amiga.lib for 2.0 (commodore 2.0 amiga.lib)
  673.     amigas20.lib    small data amiga.lib for 2.0
  674.     amigasp20.lib    small data profiled amiga.lib for 2.0
  675.     amigasr20.lib    small data registered-args amiga.lib for 2.0
  676.     amigasrp20.lib    small data registered-args + profiled amiga.lib for 2.0
  677.  
  678.     Registered users can generate any combination of models they wish by
  679.     compiling the library source code.
  680.  
  681.     DICE defaults to the small data model ('s' libraries).  Generally you
  682.     will never use the large-data model so these are not included in the
  683.     distribution (i.e. they have to be made).  Since there are a huge
  684.     number of model combinations possible the distribution itself contains
  685.     only those that are likely to be used --- to whit, small data model
  686.     libraries.    DICE has enough features in it that you should never have
  687.     to use the large-data model.
  688.  
  689.     The large-data model suffix 'l' is new.  This was added to ensure that
  690.     all combinations of models generate at least a one character suffix.
  691.     This allows DICE to give the linker hints about where to find user
  692.     libraries --- if the linker cannot find a library name unadorned it
  693.     will append the suffix and try again.  Previously, the large-data model
  694.     had no suffic so this method would not work (the large data model
  695.     library would be found even though the small-data model library is what
  696.     we wanted).
  697.  
  698.               CREATING YOUR OWN LIBRARIES
  699.  
  700.     It is extremely easy to write your own link library.  There are two
  701.     ways to do it.  First, simply compile various source modules into
  702.     objects and JOIN them together into a .lib.  Second, use the LIBMAKE
  703.     utility (see LIBMAKE.DOC).  You should name the library according to
  704.     the data model, registered args, and profiling capability you
  705.     compiled the source code for.
  706.  
  707.     For example, if you have compiled your library modules small-data
  708.     without registered arguments and no profiling and want to call your
  709.     library 'foo', you should append an 's' suffix to the library name
  710.     so the actual library file would be called 'foos.lib'.
  711.  
  712.     If you compiled the library modules small-data with registered args it
  713.     would be called 'foosr.lib'.  If you compiled it small-data with normal
  714.     args and profiling it would be called 'foosp.lib', etc... the ordering
  715.     of suffix characters is always reverse alphabetical.
  716.  
  717.     When you finally specify your library linking some program with DCC you
  718.     have two choices:    (1) you can specify the full library name such as
  719.     '-lfoosr', or (2) you can specify only the base name and let DICE pick
  720.     the suffixes for you: '-lfoo'.  The latter is the most portable, DICE
  721.     will choose the suffixes according to the various options you give DCC
  722.     when linking.
  723.  
  724.     WARNING: option (2), just specifying the base name, assumes that you do
  725.     not have a library called 'foo.lib' .. i.e. all your foo libraries have
  726.     at least one suffix character.
  727.  
  728.  
  729.  
  730.  
  731.  
  732.                PUTTING CONST DATA INTO THE CODE SEGMENT
  733.  
  734.     Two options are available to handle the 'const' keyword: -ms and -mS.  If
  735.     neither are used 'const' is ignored.  The difference between the two
  736.     determines how external references (between modules) are handled.
  737.  
  738.     With -ms, all string constants "fubar" are placed into the code segment
  739.     and referenced according to the code model (pc-rel or absolute).  Any
  740.     variable declared const will also be put in the code segment and
  741.     referenced similary.  However, any EXTERN'd variables referenced but
  742.     not defined in this module (i.e. defined in another module) will be
  743.     accessed using ABSOLUTE references, since you cannot make a jump table
  744.     for data variables.
  745.  
  746.     The -mS option is much more dangerous.. it works the same as -ms except
  747.     that external references use pc-relative addressing as well. your final
  748.     executable must be LESS THAN 32KBytes TO ENSURE ALL CODE IS REACHABLE
  749.     VIA PC-RELATIVE ADDRESSING.  If you have a choice, please use -ms
  750.     instead of -mS .
  751.  
  752.     'const __chip' variables will also be placed in the code section, but
  753.     these always use absolute references since the code section is not
  754.     combined together with other code sections.  You may also override
  755.     default access method (pc-rel/absolute) by using the __near and __far
  756.     keywords, but this is not advised.
  757.  
  758.     The -ms option affects the main compiler DC1 and can be specified
  759.     independantly for each source module (i.e. some can have it while
  760.     others do not, though normally all will have it one way or the other)
  761.  
  762.     WHEN YOU USE -pr OR -pi, use of the -ms option is silently forced to
  763.     -mS
  764.  
  765.                 RESIDENTABILITY
  766.  
  767.     Two options are available to generate residentable executables and one
  768.     option is available to genreate a non-residentable executable with no
  769.     relocation information (loads quickly).
  770.  
  771.         RES?   RELOC?   DataLim CodeLim Alloc?  Hunks
  772.  
  773.     -md     no       yes        64K(1)  none    no      DATA, CODE
  774.     -mD     no       yes        none    none    no        DATA, CODE, optionally more
  775.     -r        yes    yes        64K     none    yes     DATA, CODE
  776.     -pr     yes    no        64K     32K     yes     CODE (combined DATA+CODE)
  777.     -pi     no       no        64K     32K     no        CODE (combined DATA+CODE)
  778.  
  779.     RES:    Can this program be made resident (dlink sets Pure bit)
  780.  
  781.     RELOC:    Will this executable contain 32-bit relocations?
  782.  
  783.     DATALIM:    The maximum amount of DATA+BSS that may be declared
  784.  
  785.         (1) it is possible to declare more then 64KB worth of
  786.         data when using the small-data model by selectively
  787.         making large declarations __far.
  788.  
  789.     CODELIM:    The maximum size of the CODE
  790.  
  791.     ALLOC:    Does the startup code allocate a run time DATA+BSS segment?
  792.         (basically, resident programs must, non-resident programs
  793.         do not)
  794.  
  795.     HUNKS:    Number and type of hunks that may exist in the executable
  796.  
  797.  
  798.     -md     default
  799.  
  800.     -mD     used when final executable contains more than 64KBytes of data
  801.  
  802.     -r        most often used option
  803.  
  804.     -pr     used instead of -r if there is only a little initialized data
  805.  
  806.         Can be used with most programs but requires one large chunk of
  807.         memory instead of the two smaller chunks that -r allocates
  808.  
  809.         Also used in ROMable applications
  810.  
  811.     -pi     used instead of default when there is only a little INITIALIZED+BSS
  812.  
  813.         Can be used with many small programs that you do not intend to
  814.         make residentable, to make them load extremely fast (since there
  815.         is no relocation information).
  816.  
  817.         Also used in ROMable applications
  818.  
  819.     The __geta4 type qualifier will NOT work with residentable programs.
  820.  
  821.     You cannot use __far when accessing non-const (see -ms option) data
  822.     in residentable programs
  823.  
  824.     USING THE -ms OPTION can drastically reduce the amount of data that
  825.     needs to be allocated/copied when a resident program starts up by
  826.     moving string constants into the code section (only the data section is
  827.     duplicated), reducing overhead in both time and space for each
  828.     invocation of the RESIDENT'd program.
  829.  
  830.     To use one of the options -r, -pi, or -pr specify on the DCC line when
  831.     both compiling and linking your code.  The resulting executable will have
  832.     the pure bit set (for -r and -pr options) and be residentable.
  833.  
  834.     -r and -pr generate no BSS since the startup code is going to allocate
  835.     the DATA+BSS space.  -pi generates BSS space in the code segment just
  836.     after the initialized data.
  837.  
  838.     default    uses c.o
  839.     -r        uses c.o
  840.     -pi     uses c_pi.o
  841.     -pr     uses c_pr.o
  842.  
  843.